<html>

	<head>
		<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
		<meta name="generator" content="Adobe GoLive 4">
		<title>Coalescence for Mesquite</title>
	</head>

	<body bgcolor="#bbffbb">
		<table border="0" cellpadding="0" cellspacing="0">
			<tr>
				<td>
					<h2><img height="64" width="164" src="splash.gif"></h2>
				</td>
				<td>
					<h2>Coalescence package for Mesquite</h2>
				</td>
			</tr>
		</table>
		<p><b>Wayne Maddison</b></p>
		
<p>August 2005</p>
		
<p>This package of modules and library classes provides a few basic calculations,
  simulations and visualizations concerning gene tree coalescence in population
  genetics. There is much more that can be done,
  and opportunities for other programmers to contribute coalescence calculations
  to Mesquite.</p>
		<ul>
			<li><a href="#overview">Overview</a>
			<li><a href="#modules">Modules</a>
			<li><a href="#remaining">What remains to be done</a>
			<li><a href="#installation">Installation</a>
			<li><a href="#examples">Examples</a>
			<li><a href="#citation">Citation</a>
		</ul>
		<h3><a name="overview"></a>Overview</h3>
		
<p>Just as MacClade was designed to provide tools to ask &quot;what if the phylogenetic 
  history had been like this&quot;, Mesquite is designed to extend such questions 
  to other realms such as population genetics. Using, for instance, the insert 
  node and the lineage width tools in the Tree Window, one can construct a population 
  history with various expansions and contractions, and explore its consequences 
  on its contained gene trees via simulations.The best way to understand what 
  the package can do is to look at the <strong>example files</strong> (see below)</p>
		<p>The coalescence package currently includes:</p>
		<ul>
			<li>Simple neutral coalescence simulations. Coalescent gene trees are simulated either within a single population, or within a tree of populations/species. These simulate the gene tree itself (topology and branch lengths); to simulate nucleotide sequence data, you'll need to simulate character evolution on these gene trees using the stochastic character evolution package.
			<li>Reconstruction of the history of a gene tree within a species tree so as to minimize deep coalescences, and a tree drawing routine for species trees that draws their gene trees coalescing within them.
			<li>Counting of Slatkin &amp; Maddison's &quot;s&quot; for the discord between a gene tree and the different populations from which the genes were sampled.
			<li>Counting of &quot;deep coalescences&quot; in the style of Maddison 1997 (Syst. Biol.)
			<li>Various other modules that could be used outside of the context of coalescence, but which otherwise aren't part of the basic package of Mesquite modules (e.g., insert node, tree depth).
		</ul>
		<p>Thus, the modules are mostly focused on the topology of the gene tree and its relationship with a species tree. As shown in the examples, the package can be used to test some basic hypotheses in population genetics, especially hypotheses of population histories.</p>
		<h3><a name="conventions"></a>Conventions</h3>
		<p><b>Effective population size</b> is for the genes themselves, as if the organisms were haploid. <b>Branch lengths</b> of a population or species tree are treated as measured in units of generations. When a gene tree is drawn within a species tree, its branches are drawn <b>green</b> except if polytomies were automatically resolved to optimize fit to the species tree, in which case the resolved branches are drawn in <b>magenta</b>.</p>
		<h3><a name="modules"></a>Modules</h3>
		<p>The modules included are:</p>
		<p>Simulations:</p>
		<ul>
			<li><b>NeutralCoalescence</b> (&quot;Neutral Coalescence&quot;) -- Simulates neutral coalescence. Employed by CoalescentTrees and ContainedCoalescence in order to simulate gene trees.
			<li><b>CoalescentTrees</b> (&quot;Coalescent Trees&quot;) -- Supplies trees simulated by a coalescent process. The effective population size is a parameter that can be adjusted.
			<li><b>ContainedCoalescence</b> (&quot;Contained Coalescence within Current Tree&quot;) -- Supplies trees simulated by a coalescent process within the branches of a species tree obtained from a Tree Window or other tree context.
			<li>ContainedCoalescenceMult (&quot;Contained Coalescence in Species Trees&quot;) -- not yet ready.
		</ul>
		<p>Calculations with gene trees:</p>
		
<ul>
  <li><b>RecCoalescenceHistory</b> (&quot;Reconstruct Deep Coalescence&quot;) 
    -- Reconstructs the fit of a gene tree into a species tree so as to minimize 
    deep coalescences in the sense of W. Maddison (1997, Syst. Biol.). Also counts 
    the deep coalescence cost of such a fit. Options are (1) to treat the gene 
    tree as rooted or unrooted and (2) to allow polytomies in the gene tree to 
    resolve automatically to minimize deep coalescences further. 
  <li><b>DeepCoalescencesG</b> (&quot;Deep Coalescences (gene tree)&quot;) -- 
    Counts the cost in deep coalescences to fit a gene tree in a species tree; 
    treats this as a value for the gene tree. 
  <li><b>DeepCoalescencesSp</b> (&quot;Deep Coalescences (species tree)&quot;) 
    -- Counts the cost in deep coalescences to fit a gene tree in a species tree; 
    treats this as a value for the species tree. 
  <li><b>SlatkinMaddisonS</b> (&quot;s of Slatkin &amp; Maddison&quot;) -- Counts 
    the s value of Slatkin and Maddison (s is a measure of the discordance between 
    a gene tree and a division into populations). Requires an available Association 
    of genes into populations. 
  <li><b>TreeDepth</b> (&quot;Tree Depth&quot;) -- Determines the depth of the 
    tree, measured as the sum of branch lengths from the root to the tallest terminal 
    node. 
</ul>
		<p>Utilities:</p>
		<ul>
			<li><b>aCoalescencePkgIntro</b> (&quot;Coalescence Package Introduction&quot;) -- Introduces the coalescence package.
			<li><b>LineageWidth</b> (&quot;Adjust lineage width&quot;) -- Allows the user to adjust the widths (e.g., effective population sizes) of branches of a population or species tree. This is not merely a graphical widening, but attaches a width parameter to the branches of the tree.
			<li><b>InsertNode</b> (&quot;Insert Node&quot;) -- Inserts a node along a branch of a tree. This creates a node with only a single descendant. It can be used to break a branch into pieces, each of which is assigned its own effective population size (lineage width) and duration of time in generations (branch length).
		</ul>
		<p>The coalescence package depends on modules and libraries from the more general Taxa Associations package. The Taxa Associations package is not yet a standalone package, and is included in service of the coalescence routines. These are the included modules from the Taxa Associations package:</p>
		<p>Management and Utilities:</p>
		<ul>
			<li><b>ManageAssociations</b> (&quot;Manage TaxaAssociation blocks&quot;) -- Reads and writes TaxaAssociation blocks to NEXUS files, and supervises their editing and manipulation by users.
			<li><b>StoredAssociations</b> (&quot;Stored Taxa Associations&quot;) -- Supplies stored TaxaAssociations to calculations that need information on which taxa from one taxa block (e.g., genes) are associated with which taxa in another block (e.g., species).
			<li><b>ManageDistributionBlock</b> (&quot;Read DISTRIBUTION blocks&quot;) -- Reads DISTRIBUTION blocks (e.g., used by Rod Page's GeneTree) in NEXUS files. Subsequent writing of the information is currently to separate TAXA, TREES and TaxaAssociation blocks.
		</ul>
		<p>Graphics and analysis:</p>
		<ul>
			<li><b>ContainedAssociates</b> (&quot;Contained Associates&quot;) -- Draws a species tree with broad branches, inside which are reconstructed and drawn gene trees within them.
		</ul>
		<h3><a name="remaining"></a>What remains to be done</h3>
		<p>Improvements to the existing modules remain to be made, including making
	  them more efficient.</p>
		<p>Many other calculations taking a gene tree perspective could be done, including
		  those that have nucleotide sequence evolution occurring along the branches
		  of the gene tree. This would allow direct comparison against observed
		  sequences, without being forced to reconstruct a gene tree from the
		  sequences before
		  comparison with Mesquite's results. The solution to this will come
		  from the Genesis package, which can be combined with the coalescence
		  package to generate
		  nucleotide sequences evolved on coalescence trees.</p>
		<h3><a name="installation"></a>Installation</h3>
		
<p>There are two folders (directories) whose contents need to be in the correct 
  place for Mesquite to be able to use them. These two directories are called 
  (1) &quot;coalesce&quot; and (2) &quot;assoc&quot;. Find where you have Mesquite 
  installed on your hard disk. These three directories should be in the &quot;mesquite&quot; 
  directory within &quot;Mesquite Folder&quot;.</p>
		<h3><a name="examples"></a>Examples</h3>
		<p>There is a series of example data files in the directory &quot;coalescence_examples&quot;. The files are self explanatory; begin with the file whose name begins with &quot;00&quot;.</p>
		<p>
		<hr noshade size="2">
		</p>
		
<p>&copy; Copyright 2002-2005 W. Maddison 
</body>

</html>
